ATSUGetAttribute

OSStatus ATSUGetAttribute (
                     ATSUStyle iStyle,
                     ATSUAttributeTag iTag,
                     ByteCount iMaximumValueSize,
                     ATSUAttributeValuePtr oValue,
                     ByteCount *oActualValueSize);

iStyle

A reference of type ATSUStyle. Pass a reference to a valid style object whose attribute value you want to obtain. You cannot pass NULL for this parameter.

iTag

An array of values of type ATSUAttributeTag. Pass a valid tag that corresponds to the style run attribute value you wish to determine. See Style Run Attribute Tag Constants for a description of the Apple-defined style run attribute tag constants. If you pass a text layout attribute tag constant or an ATSUI-reserved tag constant in this parameter, ATSUGetAttribute returns the result code kATSUInvalidAttributeTagErr. You cannot pass NULL for this parameter.

iMaximumValueSize

The maximum size of the style run attribute value. To determine the size of an application-defined style run attribute value, see the discussion below. If you pass a size that is less than required, ATSUGetAttribute returns the result code kATSUInvalidAttributeSizeErr.

oValue

A pointer of type ATSUAttributeValuePtr. Before calling ATSUGetAttribute, pass a pointer to memory you have allocated for the attribute value. If you are uncertain of how much memory to allocate, see the discussion below. On return, oValue points to the style run attribute value. If the attribute was not previously set, ATSUGetAttribute passes back its default value in this parameter and returns the result code kATSUNotSetErr.

oActualValueSize

A pointer to a count. On return, the actual size (in bytes) of the attribute value. You should examine this parameter if you are unsure of the size of the attribute value you wish to obtain, as in the case of custom style run attributes.

function result

A result code. See Result Codes.

DISCUSSION

Before calling the ATSUGetAttribute function, call the function ATSUGetAllAttributes to obtain an array of the tags and data sizes corresponding to all previously set style run attribute values in a style object. To determine the value of a style run attribute identified by a particular style run attribute tag, you should pass the appropriate tag and data size pair passed back in the oAttributeInfoArray array of ATSUGetAllAttributes to ATSUGetAttribute.

If you do not know the size of the style run attribute value you wish to determine, call ATSUGetAttribute twice:

Pass a reference to the style object containing the attribute in the iStyle parameter, NULL for the oValue parameter, and 0 for the other parameters. ATSUGetAttribute returns the size of the attribute value in the oActualValueSize parameter.
Allocate enough space for a value of the returned size, then call the function again, passing a pointer in the oValue parameter; on return, the pointer references the attribute value.

VERSION NOTES

Available beginning with ATSUI 1.0.